| Syntax | Description | |
|---|---|---|
| %title% | Title of the track. If ΓÇ£titleΓÇ¥ metadata field is missing, file name is used instead. | |
| %artist% | Name of the artist of the track. Checks following metadata fields, in this order: ΓÇ£artistΓÇ¥, ΓÇ£album artistΓÇ¥, ΓÇ£composerΓÇ¥, ΓÇ£performerΓÇ¥. | |
| %album artist% | Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: ΓÇ£album artistΓÇ¥, ΓÇ£artistΓÇ¥, ΓÇ£composerΓÇ¥, ΓÇ£performerΓÇ¥. The difference between this and %artist% is that %album artist% is intended for use where consistent value across entire album is needed even when per-track artists values vary. | |
| %track artist% | Name of the artist of the track; present only if %album artist% is different than %artist% for specific track. Intended for use together with %album artist%, to indicate track-specific artist info, e.g. ΓÇ¥%album artist% - %title%[ '//' %track artist%]ΓÇ¥ - in this case, last part will be displayed only when track-specific artist info is present. | |
| %album% | Name of the album specified track belongs to. Checks following metadata fields, in this order: ΓÇ£albumΓÇ¥, ΓÇ£venueΓÇ¥. | |
| %date% | Recording date (year) of the album specified track belongs to, using ΓÇ£dateΓÇ¥ metadata field. | |
| %genre% | Genre of the album specified track belongs to, using ΓÇ£genreΓÇ¥ metadata field. | |
| %tracknumber% | Two-digit index of specified track within the album. Available only when ΓÇ£tracknumberΓÇ¥ field is present in trackΓÇÖs metadata. | |
| %totaltracks% | Two-digit number of tracks within the album specified track belongs to. Available only when ΓÇ£totaltracksΓÇ¥ field is present in trackΓÇÖs metadata. | |
| %discnumber% | Index of disc specified track belongs to, within the album. Available only when ΓÇ£discnumberΓÇ¥/ΓÇ£discΓÇ¥ field is present in trackΓÇÖs metadata. | |
| %totaldiscs% | Number of discs within the album specified track belongs to. Available only when ΓÇ£totaldiscsΓÇ¥ field is present in trackΓÇÖs metadata. | |
| %codec% | Name of codec used to encode the track. If exact codec name is not available, file extension is used. | |
| %codec_profile% | Additional information about encoding settings used. Not always available. | |
| %filename% | Name of file, excluding directory path and extension. | |
| %filename_ext% | Name of the file, including extension but excluding directory path. | |
| %directoryname% | Name of the directory the file is in. | |
| %path% | Full path of the file. Note that %path_sort% should be use for sorting instead of %path%. | |
| %subsong% | Index of the track within the file, for use with file formats that support multiple tracks within single physical file (e.g. chapters or a cuesheet). | |
| %path_sort% | Path of the file; for use with sorting, where order of subsongs within a file needs to be preserved; exact value returned by it is undefined and should not be relied on. | |
| %length% | Length of the track, formatted as [HH:]MM:SS. | |
| %length_seconds% | Length of the track, in seconds, formatted as an integer. | |
| %bitrate% | Bitrate of the track in kilobits per second (kbps); includes dynamic VBR bitrate display for currently played track. | |
| %channels% | Number of channels in the track (mono/stereo/etc). | |
| %samplerate% | Sample rate of the track, in Hz. | |
| %replaygain_track_gain%, %replaygain_album_gain%, %replaygain_track_peak%, %replaygain_album_peak% | ReplayGain information. | |
| %filesize% | Size of the file, in bytes. | |
| %filesize_natural% | Size of the file, automatically formatted in appropriate units such as megabytes or kilobytes. | |
| %last_modified% | Last modification time of the file, formatted as YYYY-MM-DD HH:MM:SS. | |
The above list is not complete, there are other less relevant fields as well as generic %field% ⇒ metadata and %__field% ⇒ tech info remappings provided for backwards compatibility.
| Syntax | Description |
|---|---|
| %list_index% | Index of the item on the list it belongs to. Applies to: playlist, list of items processed by masstagger/massrenamer, etc. Padded with zeros to match max. width of possible index within the list. |
| %list_total% | Number of items on the list specified item belongs to. Applies to: playlist, list of items processed by masstagger/massrenamer, etc. |
| %isplaying% | Present if e.g. a playlist item is currently being played, absent otherwise. Meant to be used as a switch for $if(). |
| %ispaused% | Present if e.g. a playlist item is currently being played and is paused, absent otherwise. Meant to be used as a switch for $if(). |
| %playback_time% | Current playback time, formatted as [HH:]MM:SS. Available only in contexts where playback related data is displayed, such as statusbar. |
| %playback_time_seconds% | Current playback time, in seconds, formatted as integer. Available only in contexts where playback related data is displayed, such as statusbar. |
| %playback_time_remaining% | Remaining playback time, formatted as [HH:]MM:SS. Available only in contexts where playback related data is displayed, such as statusbar. Not available when duration of currently playing track is not known. |
| %playback_time_remaining_seconds% | Remaining playback time, in seconds, formatted as integer. Available only in contexts where playback related data is displayed, such as statusbar. Not available when length of currently playing track is not known. |
| %queue_index% | Index of the specified item in the playback queue; available in playlist only. If the item has been queued multiple times, %queue_index% evaluates to the first index. |
| %queue_indexes% | List of indexes of the specified item in the playback queue; available in playlist only. Same as %queue_index% unless the item has been queued more than once. |
| %queue_total% | Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons. |
| Syntax | Description | Example |
|---|---|---|
| $abbr(X) | Returns an abbreviation of X. | $abbr(%album%) |
| $abbr(X,Y) | Returns an abbreviation of X if X is longer than Y characters; otherwise returns full value of X. | $abbr(%album%,5) |
| $ansi(X) | Returns X with all characters not present in current system codepage replaced with closest matches. Useful for sanitizing filenames when interacting with other software that can't handle Unicode. | $ansi(%title%), $ansi(%filename%) |
| $ascii(X) | Returns X with all non-ASCII characters replaced with closest ASCII matches. Useful for sanitizing filenames when interacting with other software that can't handle Unicode. | $ascii(%title%), $ascii(%filename%) |
| $lower(X), $upper(X) | Converts X to lower/uppercase. | $upper(%title%) |
| $num(X,Y) | Displays X as a number and pads with zeros up to Y characters (useful for track numbers etc). | $num(%tracknumber%,3) |
| $caps(X) | Converts first letter in every word of X to uppercase, and all other letters to lowercase, e.g. ΓÇ£blah BLAHΓÇ¥ ⇒ ΓÇ£Blah BlahΓÇ¥. | $caps(%title%) |
| $caps2(X) | Similar to $caps, but leaves uppercase letters as they are, e.g. ΓÇ£blah BLAHΓÇ¥ ⇒ ΓÇ£Blah BLAHΓÇ¥. | $caps2(%title%) |
| $if(X,Y,Z) | If X contains at least one present field, executes/displays Y, otherwise executes/displays Z. | $if(%artist%,%artist%,unknown artist) |
| $if2(X,Y) | Same as $if(X,X,Y). | |
| $if3(X,Y,Z,..) | Returns the first of parameters that contains at least one present field. | |
| $ifgreater(A,B,C,D) | If the number A is greater than the number B, executes/returns C, otherwise executes/returns D. | |
| $iflonger(A,B,C,D) | If the string A is longer than B characters, executes/returns C, otherwise executes/returns D. | |
| $ifequal(A,B,C,D) | If the number A is equal to the number B, executes/returns C, otherwise executes/returns D. | |
| $longest(A,B,C,….) | Compares lengths of of A,B,C… and returns the longest one. | $longest(%title%,%filename%) |
| $len(X) | Returns length of the string X in characters. | |
| $pad(X,Y), $pad_right(X,Y) | Pads X with spaces up to Y characters. | |
| $pad(X,Y,Z), $pad_right(X,Y,Z) | Pads X with Z character up to Y characters. | |
| $cut(X,Y) | Truncates X to Y characters. | |
| $padcut(X,Y), $padcut_right(X,Y) | Pads X to Y characters and truncates to Y if longer. | |
| $insert(A,B,N) | Inserts string B into string A after N characters. | |
| $add(X,Y), $sub(X,Y), $mul(X,Y), $div(X,Y), $mod(X,Y), $min(X,Y), $max(X,Y) | Various math operations. | |
| $left(X,Y) | Returns Y first characters of string X. | |
| $right(X,Y) | Returns Y last characters of string X. | |
| $and(X,Y), $or(X,Y), $xor(X,Y), $not(X) | Various logical operations, for use with $if(). | |
| $fix_eol(x), $fix_eol(x,y) | Truncates multiline strings, adding ΓÇ¥ (…)ΓÇ¥ (version 1) or y (version 2) at the end. | |
| $meta(X) | Returns value of metadata field named X. | $meta(artist) |
| $meta_sep(X,Y), $meta_sep(X,Y,Z) | Returns metadata field named X, with custom separators for multiple values | $meta(artist,', ',' and ') ⇒ ΓÇ£artist1, artist2 and artist3ΓÇ¥ |
| $meta_num(X) | Returns number of present values for metadata field X. | |
| $info(X) | Returns tech info field named X. | $info(bitrate) |
| $char(X) | Inserts Unicode character no. X. | $char(9674) |
| $strcmp(X,Y) | Returns ΓÇ£1ΓÇ¥ when strings X and Y are identical, empty string otherwise; intended for use with $if(). | |
| $stricmp(X,Y) | Non-case-sensitive version of $strcmp(X,Y). | |
| $directory(X), $directory(X,N) | Extracts directory name from the file path X, optionally goes up by N directory levels. | $directory(%path%,2) |
| $directory_path(X) | Extracts directory path from the file path X. | $directory_path(%path%) |
| $greater(X,Y) | Compares two integers, tests if X>Y, intended for use with $if() and logical operators. | |
| $longer(X,Y) | Compares two strings, tests if X is longer than Y, intended for use with $if() and logical operators. | |
| $strchr(X,Y) | Finds first occurrence of character Y in string X. | |
| $strrchr(X,Y) | Finds last occurrence of character Y in string X. | |
| $strstr(X,Y) | Finds first occurrence of string Y in string X. | |
| $select(N,A,B,C,….) | Returns N-th of A,B,C… parameters. | |
| $repeat(X,N) | Repeats X N times. | |
| $replace(A,B,C) | Replaces all occurrences of string B in string A with string C. | |
| $ext(X) | Extracts extension from file path / file name. | $ext(%path%) |
| $substr(A,B,C) | Returns substring of string A, starting from B-th character and ending at C-th character | $substr(blah,1,2) ⇒ ΓÇ£blΓÇ¥ |
| $trim(A) | Trims leading/trailing space characters from A. | $trim(%title%) |
| $tab() | Generates a tab character; equivalent to $char(9). See ΓÇ£tab characterΓÇ¥ explanation below for more info about its use. | $tab() |
| $stripprefix(X) | Removes ΓÇ£AΓÇ¥ and ΓÇ£TheΓÇ¥ prefixes from X. | $stripprefix(%artist%) ⇒ ΓÇ£The ProdigyΓÇ¥ becomes ΓÇ£ProdigyΓÇ¥ |
| $stripprefix(X,prefix1,prefix2,…) | Removes the specified prefixes from X. | $stripprefix(%artist%,a,the) ⇒ ΓÇ£The ProdigyΓÇ¥ becomes ΓÇ£ProdigyΓÇ¥ |
| $swapprefix(X) | Moves ΓÇ£AΓÇ¥ and ΓÇ£TheΓÇ¥ prefixes to the end of X. | $swapprefix(%artist%) ⇒ ΓÇ£The ProdigyΓÇ¥ becomes ΓÇ£Prodigy, TheΓÇ¥ |
| $swapprefix(X,prefix1,prefix2,…) | Moves the specified prefixes to the end of X. | $swapprefix(%artist%,a,the) ⇒ ΓÇ£The ProdigyΓÇ¥ becomes ΓÇ£Prodigy, TheΓÇ¥ |
| $year(time) | Retrieves the year part (formatted as four digits) from a time/date string. | $year(%last_modified%) |
| $month(time) | Retrieves the month part (formatted as two digits) from a time/date string. | $month(%last_modified%) |
| $day_of_month(time) | Retrieves the day of month part (formatted as two digits) from a time/date string. | $day_of_month(%last_modified%) |
| $date(time) | Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string. | $date(%last_modified%) |
| $time(time) | Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string. | $time(%last_modified%) |
| Syntax | Description | Example |
|---|---|---|
| $put(name,text) | Sets the variable named name to text and returns text. | ΓÇ£$put(x,blah)ΓÇ¥ sets variable x to ΓÇ£blahΓÇ¥ and returns ΓÇ£blahΓÇ¥. |
| $puts(name,text) | Silent version of $put(). Same as $put(name,text), but returns an empty string. | |
| $get(name) | Returns the value of the variable named name or an empty string if such variable hasn't been set. | ΓÇ£$puts(x,blah)$get(x)$get(x)ΓÇ¥ returns ΓÇ£blahblahΓÇ¥ |
| Syntax | Description | Example |
|---|---|---|
| [ …. ] | Discards contents of the bracket when no fields referenced inside are present. Commonly used to create parts of formatting scripts that are active only when relevant fields are found. | %artist% - [%album% / ]%title% |
| ' (single quotation mark) | Inserts specified text bypassing syntax processing; allows special characters such as %,$,[,] to be inserted. In order to insert a quotation mark character, use '' (two single quotation marks). | |
| // | Comments, can be placed only at the beginning of a new line; prevent any characters following them until the end of line from being parsed. | |
| End-of-line characters | Ignored; you can make your script more readable by splitting it into multiple lines, without affecting its output. | |
| Tab character | Used to control text alignment in certain contexts such as status bar. See also: $tab(). | %title%$tab()%length% |
| Color control: < > | Used to dim or highlight text, currently available in playlist and status bar. There are 3 dim and 3 highlight levels, accessible by repeating color control characters. | <dim> >highlight< >>extrahighlight<< |